home *** CD-ROM | disk | FTP | other *** search
/ L' Effet Pommier 3 / L'Effet Pommier - Volume 03.iso / Graphismes / 3D / POV-Ray 3.0B5a PPC / POV-Ray 3.0B5a / POVDOC.Documentation / POV-Ray 3 Mac Docs < prev    next >
Text File  |  1996-02-20  |  46KB  |  820 lines
  1. POV-Ray 3.0
  2. for the
  3. Macintosh
  4. The Very Best
  5. Freeware Macintosh Ray Tracer
  6. Version 3.0 Beta 5a
  7. February 20, 1996
  8.  
  9. \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
  10. NOTES:
  11. -This beta software is metered, and will expire April 1996.
  12. -This documentation is a quick collection of the old 2.2 Mac docs,
  13.  and is being converted to 3.0 information.  I'm working from the
  14.  top down, so good stuff is at the top, stale stuff is at the end.
  15. --Eduard Schwan
  16. /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
  17.  
  18. Welcome to POV-Ray for the Macintosh!  This software is called a ray tracer.  POV-Ray reads a text file 
  19. that contains information describing the objects and lighting in a scene, and it generates an image of that 
  20. scene from the view point of a camera also described in the text file.  The creation of these images and 
  21. animations by ray tracing is not a fast process by any means, but it produces very high quality images with 
  22. realistic reflections, shading, perspective, and other effects.  This program is Freeware.  For more 
  23. information on the usage and distribution policies of POV-Ray, please see POVLEGAL.DOC.
  24.  
  25. Introduction
  26. This document describes the specific functions of the Macintosh version of POV-Ray.  You will also need 
  27. to read the POVRAY.DOC file, which describes the general operation of POV-Ray, and describes its 
  28. features and language.
  29.  
  30. Compatibility
  31. Here are POV-Ray's requirements of hardware and software, and some of its features:
  32.  
  33. Minimum daily requirements for 68K Macintosh:
  34. 68020/68030/68040 CPU (e.g., Mac II, Centris, Quadra, etc.)
  35. 68881 Floating Point Unit (FPU) required (Can use Software FPU instead)
  36. System 7
  37. Minimum 8 MB RAM in computer
  38.  
  39. Minimum daily requirements for Power Macintosh:
  40. 601/603/604 PPC CPU (e.g., 6100, 7200, 8500, 9500, etc.)
  41. System 7
  42. Minimum 16 MB RAM in computer
  43.  
  44. Features:
  45. Saves final images as 24-bit PICT files (and Targa, PNG, or Unix PPM files)
  46. Can create animation image sequences for making Director or QuickTime movies
  47. System 7 Savvy
  48. Accelerated for Power Macintosh
  49. Built-in mini text editor with multiple undo, for editing scene files
  50. ╥Templates╙ allow instant inserting of any scene elements into file
  51. Works with System 7's Virtual Memory
  52. Intelligent support of multiple monitors (dialogs follow the Status Window)
  53. Can run in the background, background cooperation is configurable
  54. Auto-Shutdown feature, can auto-save and shut down Mac when rendering is done
  55. Handles System 7 Required AppleEvents
  56. Multiple source files can be dropped on to do batch rendering
  57. Can add System 7 custom Finder icons to rendered PICT files
  58. <??System 7 Balloon Help throughout?? - to do>
  59. Status window contents can be copied to clipboard or saved to text file
  60. <??Can optionally QuickTime-compress final PICT files?? - to do>
  61.  
  62. Where do I start?
  63. To get started right away, follow the steps 1 through 4.  These will guide you through installing the 
  64. software, configuring it, and creating your first ray traced picture.
  65.  
  66. 1. Install
  67. First, you must determine which application you need for your Macintosh... do you have a Power 
  68. Macintosh?  If so, you should get the POVPMAC.SIT archive, otherwise get the POVMAC68.SIT 
  69. archive.
  70.  
  71. Decide where to install POV-Ray and its associated files.  There are no restrictions on where the files can 
  72. go, but you will need to insure you have enough available disk space to install.  The archives are fairly 
  73. large, and the extracted files and directories are quite a bit larger still.  The archives are "Stuffit" format 
  74. files, which means that you will need a copy of Stuffit Expander 3.5 (freeware), Stuffit Lite 3.5 
  75. (shareware), or Stuffit Deluxe (commercial) from Aladdin Systems to expand the archives.
  76.  
  77. The following table will give you an idea of how much free hard disk space you will need for expanding 
  78. the archives:
  79. Archive Name    Archive Size    Expands to about
  80. -----------     ------------    ----------------
  81. POVPMAC.SEA     1.2 MBytes      4 MBytes
  82. POVMAC.SEA      1.2 MBytes      4 MBytes
  83. POVMSRC.SEA     600 KBytes      2.2 MBytes
  84.  
  85. So, as a bare minimum, you will need about 4 MBytes free for the POV-Ray folder.
  86.  
  87. Now extract the POV-Ray application from the POVPMAC (or POVMAC68) archive using your favorite 
  88. Stuffit tool.  It would be a good idea to open the POVDOC.Documentation folder and do a quick browse 
  89. of the first part of the POVRAY.DOC manual now, before going too much farther.
  90.  
  91. 2. Configure
  92. POV-Ray 3.0 automatically configures itself to your Macintosh, so there is not much you need to do prior 
  93. to running it.  If you will be rendering large (800x600 or bigger) images, or moving the INCLUDE folder 
  94. from its current home in the POVDOC folder, then you will need to read "Advanced Topics" later in this 
  95. document.
  96.  
  97. 3. Double-click
  98. You are now ready to run POV-Ray.  To render an existing source file, like one of the demo or sample 
  99. files, do the following:
  100.  
  101. 3a.    Double-click POV-Ray and use ╥Open╙ from the File menu to open the scene file.  Under System 7, 
  102. you can also drag the source file over and drop it onto the POV-Ray application.  This will run POV-
  103. Ray and automatically open the source file.  Note that the POV-Ray editor can only open ONE 
  104. source file at a time.  If you drop multiple files onto POV-Ray, it will start automatically rendering 
  105. each file and saving each image to a separate image file.  This is another great feature in itself, but 
  106. probably not what you wanted to do just yet!  This ╥batch-rendering╙ feature is covered in the file 
  107. "POV-Ray 2.0 Notes", under Advanced Tips.
  108.  
  109. 3b.    Choose ╥Rendering Options╙ from the Render menu, and fill out the dialog with the options you 
  110. want (see POVRAY.DOC or use System 7 Balloon Help for more information on these.)  For now, 
  111. you may want to choose the ╥32x32╙ or ╥64x64╙ image presets from the popup menu, to pick a 
  112. small, quick render.
  113.  
  114. 3c.    Choose the ╥View╙ - ╥Normal╙ item from the ╥Image╙ menu, so the output image is shown as it 
  115. renders.
  116.  
  117. 3d.    Choose ╥Render╙ from the Render menu, and POV-Ray will read and ╥parse╙ the source file, and 
  118. then create an output image.
  119.  
  120. 3e.    When it completes, you may copy the image to the clipboard.  Make sure the image window is in 
  121. front, and select ╥Copy╙ from the Edit menu.  You can also save the image as a PICT file, by 
  122. choosing ╥Save╙ or ╥Save As╙ from the File menu.
  123.  
  124. #####  or, for the more adventurous  ######
  125.  
  126. 4. Create a New Scene File
  127. To create a new source file of your own, just double-click POV-Ray, or choose ╥New╙ from POV-Ray's 
  128. File menu if it is already running.  You are presented with an ╥Untitled.POV╙ Source window, and the 
  129. Status window.  You would then do the following to create and render a new file:
  130.  
  131. 4a.    Type some POV-Ray source statements into the Source window.  A very useful built-in aid for 
  132. automating this is an item hiding under the Edit menu, ╥Insert Template╙.  This hierarchical menu 
  133. contains syntactically correct ready-to-use text for every POV-Ray statement.  You just choose one 
  134. (camera, light_source, texture, sphere, etc.) and it will insert it right into your source file wherever 
  135. your cursor is.  You just edit the parameters after that to tailor it.
  136.  
  137. 4b.    Save the file to disk (choose ╥Save╙ under the File menu).  Note that the renderer expects the file to 
  138. be saved to disk, and you cannot set the rendering options or start rendering until you do this.
  139.  
  140. 4c.    Choose ╥Rendering Options╙ from the Render menu, and fill out the dialog with the options you 
  141. want.  See the "Rendering Options" section of the POV-Ray 2.0 Notes document for more 
  142. information on this dialog.
  143.  
  144. 4d.    Choose the ╥View╙ - ╥Normal Size╙ item from the Image menu.
  145.  
  146. 4e.    Now choose ╥Render╙ from the Render menu, and your source file will be read and ╥parsed╙, and if 
  147. there were no errors, an output image will start to be generated.
  148.  
  149. 4f.    If POV-Ray finds an error in your source file, it will display an error dialog, write a description of 
  150. the error to the Status window, and automatically select the source line in error, for you to fix.  You 
  151. can fix the line, save the updated file to disk (press command-S), and re-render the scene.
  152.  
  153. Other Files
  154. In addition to the application, you should also find other POV-Ray archives with the following contents:
  155. POVSRC.SEA - Think C, Metrowerks, and MPW C compatible Macintosh Source Code for POV-Ray.
  156.  
  157. Macintosh Program Notes
  158. Following is a hodge-podge of information on the Macintosh-specifics of this program.
  159.  
  160. User Interface
  161. The implementation of POV-Ray on the Macintosh is quite a leap from the command-line interface of 
  162. POV-Ray on most other platforms.  The core code of POV-Ray is identical (including the command line 
  163. parameter passing), but all of that is hidden from the user, and a more convenient ╥Graphical User 
  164. Interface╙ is provided, with all the menus, windows and dialog boxes you'd expect from a serious 
  165. Macintosh application.
  166.  
  167. Memory Size
  168. Ray tracing generally uses a LOT of RAM memory to store all the elements of a scene.  POV-Ray Mac 
  169. initially comes with an application memory size set at 3,000 Kilobytes.  This size is sufficient to render all 
  170. of the standard example files with room to spare.  For less complex images, POV-Ray can render small 
  171. scenes effectively in a memory partition as small as 1,000K.  The vast majority of the example scene files 
  172. will render in 2,000K.  To change POV's memory size, click once on the POV-Ray program icon from the 
  173. Finder, then choose ╥Get Info╙ from the File menu.  The (preferred) application memory size is in a box in 
  174. the lower right corner of the window, and can be edited.  The value is in Kilobytes, so for example, to 
  175. change it to 6 megabytes (approximately 6,000 Kilobytes,) you would enter 6000.
  176.  
  177. The Windows
  178. POV-Ray Mac has three windows.  The ╥Status╙ Window shows progress and statistics during the 
  179. rendering process.  The ╥Source╙ Window shows the scene text file to be rendered, and acts as a simple 
  180. text editor.  The ╥Image╙ Window is where the final image is generated during rendering.  Text from the 
  181. Status and Source windows can be copied and pasted via the clipboard, and the picture in the Image 
  182. window can also be copied to the clipboard.
  183. NOTE: When creating a new untitled source file, you must first save it to a disk file before you can set its 
  184. options or render it.
  185.  
  186. Output Image Memory
  187. POV-Ray tries to store the output image entirely in RAM memory while rendering.  Since the image 
  188. requires approximately Width x Height x 4 bytes of memory, sometimes this is not possible.  For 
  189. example, a 640 x 480 image needs about 1.25 megabytes of RAM.  When POV-Ray finds that it can not 
  190. hold the image in RAM, it will hold it in a temporary disk file, and swap it in to a smaller RAM buffer a 
  191. few scan-lines at a time.  This lets you create very large (4096x4096 theoretically!) images with limited 
  192. RAM, at the cost of slower rendering time and more disk I/O.  This is referred to in POV-Ray Mac as the 
  193. ╥Virtual Image Buffer╙ or VIB.  To avoid increased wear and tear on your hard disk, and to speed up 
  194. rendering times on large images, you can allocate more application memory to POV-Ray, to avoid the use 
  195. of the Virtual Image Buffer.  If you do not have enough memory in your Mac and must use it, you can 
  196. speed things up some by hiding the image window while it renders.
  197.  
  198. Output image Disk Space
  199. The final images require a fair amount of disk space as well.   A final 640x480 PICT image file can take up 
  200. to 500 KBytes on disk.  If you turn on the "Create Targa Output File" option in the File Rendering 
  201. Preferences, this separate Targa file can take an additional 1 MByte for a 640x480 image.  Keep this in 
  202. mind so you don't run out of disk space before the image completes.
  203.  
  204. System 7 Virtual Memory Delays
  205. If you are using System 7's virtual memory (VM), particularly for extremely complex scenes, you may 
  206. notice very large delays during parsing.  This is due to the way the memory allocation, the parser, and 
  207. Apple's VM system interact.  Once parsing has finished, actual rendering time should be fairly comparable 
  208. to non-VM systems.
  209.  
  210. Preference files and Virtual Image Buffer (VIB) files
  211. POV-Ray automatically creates two special types of files during its operation.  The first is ╥POV-Ray 
  212. Preferences,╙ which is a small file which will be put inside your System Folder (in the Preferences folder 
  213. if you use System 7.)  It should be left there, as it stores important user settings for POV-Ray.  These 
  214. settings can be changed by choosing the POV-Ray Preferences menu item in the Edit menu.  If this file is 
  215. moved or deleted, POV-Ray will create a new one with default values.  One of the things that will need to 
  216. be reconfigured if this happens is the ╥Include Paths╙ settings.  The other file is called ╥POV-Ray.vib,╙ 
  217. which is only used during rendering of large images.  This is the Virtual Image Buffer file, and is only 
  218. used while POV-Ray is rendering an image.  So if for some reason you notice this large file left behind 
  219. after POV-Ray quits, it is OK - and suggested - that you delete it.
  220.  
  221.  
  222. Credits and Blame
  223. This Mac front end has a long and sordid history... I will tell you what I know.
  224.  
  225. Eduard Schwan created 2.0 by extensively modifying Jim Nitchals' 1.0 version, which was an extensive 
  226. modification of an earlier version written by Thomas Okken.  A few other ideas were gleaned from an 
  227. even earlier Macintosh version built by Glenn Sugden.  Mac things get awfully fuzzy and primordial 
  228. before that.
  229.  
  230. Dave Harr did the original 1.0 Balloon Help, helped design some user interface changes, and added the 
  231. custom palette code.
  232.  
  233. Jim Nitchals added the mini text editor with multiple undo, and invented the virtual image buffer swapping 
  234. code, and the first version of the PICT file saving package.  Jim also improved the POV-Ray multitasking 
  235. and memory management (COOPERATE and POV_Malloc) to allow multiple renderings without having 
  236. to quit the program between renders.  He also synthed up the ╥Done╙ boing sound.
  237.  
  238. Eduard [esp] Schwan ported the code from Think C 5 and built and tested it in MPW C, revamped the user 
  239. interface one more time (and had to continually rewrite Balloon Help to match), invented some code for a 
  240. generic status window that captured ╥printf╙s for both Think and MPW, got the AppleEvent stuff to work, 
  241. worked on the memory management, added QuickTime Image Compression, rewrote the prefs code, 
  242. added multi-file drag-n-drop, added the Mac animation support, retested and rebuilt the Think C 6 version, 
  243. re-worded this document, and bombarded Jim and other team members with late night calls, bug reports, 
  244. source changes, and wild suggestions.
  245.  
  246. Anton Raves relentlessly put the Beta POV-Ray 2.0 through its paces, and found all sorts of ╥unexpected 
  247. features╙ in the program.  Many thanks for his tireless efforts, great suggestions, and imperceptible Dutch 
  248. accent!
  249.  
  250. Mark de Jong complained about all sorts of documentation and user interface abominations in the Beta 2.0 
  251. version, and really kept me on my toes.
  252.  
  253. Jim would like to thank his wonderful wife and best friend, Cindy, for her support while he was coding 
  254. and rendering many late nights.  Thanks!
  255.  
  256. Eduard would like to thank Lorrie, Bryon, Sara, Sushi, and V.G.s (patient wife, impatient 5 year old son, 
  257. brand-new daughter, oblivious lap cat, and super donut shop) for sticking around while the bugs and 
  258. pixels were thickest.
  259.  
  260. Jim wishes there was a VG.'s nearby.  They DO make the best donuts and also baked Cindy's and his 
  261. wedding cake.
  262.  
  263. Encore... more info please!
  264. Where to get more info...
  265.  
  266. 1.    Refer to the POV-Ray documentation for general information on the scene description language, and 
  267. general theory of operation.  This is contained in the included POVDOC archive.
  268.  
  269. 2.    For a superb in-depth discussion of the POV-Ray raytracer (version 2.2), you should get a copy of 
  270. the book, "Ray Tracing for the Macintosh CD", by Eduard Schwan, published by the Waite Group 
  271. Press, ISBN 1-878739-72-7...
  272. blah blah...
  273.  
  274. 3.    For on-line information, new files, and technical support, join Compuserve's Graphics Developers 
  275. forum (GRAPHDEV), or America Online's Company Support area of the PC Graphics Forum 
  276. (keyword: "PGR").
  277.  
  278. 4.    There are many utility programs out there that convert files to POV-Ray format or create POV-Ray 
  279. objects.  A handful of these utilities was ported to the Macintosh, and is on Compuserve and 
  280. America OnLine as the "Macintosh POV-Utilities", ported by Eduard [esp] Schwan.  These are 
  281. worth checking out.  Updates to these are planned in the near future.
  282.  
  283. 5.    For Macintosh-specific issues, please feel free to contact one of us directly:
  284.  
  285. Eduard [esp] Schwan can be reached on:
  286. Compuserve: 71513,2161
  287. Internet:   71513.2161@compuserve.com
  288. US Mail:  1112 Oceanic Drive, Encinitas, California, USA, 92024-4007
  289. (I check Compuserve every day or so.  The Internet accounts are, as you can tell, simply gateways to my 
  290. Applelink or CIS accounts.  Note that I am charged per kilobyte for any e-mail sent or received through the 
  291. internet gateway, so please don╒t send any large binhexed files unless you ask first.)
  292.  
  293. Note: When sending us questions via e-mail, we would like to assume that your question can be re-posted 
  294. publically in other online forums along with the reply.  This way others can benefit from your experience.  
  295. If you don't want your question posted publicly, no problem, just let us know.
  296.  
  297. What's New
  298. BIG NOTE: Only some of the POV-Ray archives have needed changes since version 2.0, the others are 
  299. remained at version 2.0.  Here are the most current versions of each of the archives:
  300. POVDOC.SEA - 2.0
  301. POVMAC.SEA - 2.2
  302. POVMNF.SEA - 2.2
  303. POVSCN.SEA - 2.0
  304. POVSRC.SEA - 2.2
  305.  
  306. What's new in version 2.2?
  307. There were many complaints that POV-Ray's "SmartMalloc" progress between renders was between 5 and 
  308. 10 minutes!  This is due to 2 factors: The use of Mac memory management (instead of C memory 
  309. management), and the fact that auto-bounding was defaulted to ON which uses lots of memory.  I have 
  310. temporarily returned to C's memory management, which is faster but __doesn't completely free up 
  311. memory__, and defaulted auto-bounding to be OFF.  This is a temporary fix until we have no more 
  312. memory leaks in the code and can do away with SmartMalloc altogether (v3.0)! 
  313.  
  314. Core bugs fixed: (See also "WHATSNEW.DOC")
  315.   - Fixed problem with declared material_maps or declared objects with
  316.     material_maps (yet again)
  317.   - Eliminated unnecessary turbulence calculations in normals
  318.   - Fixed all known problems with height fields
  319.  
  320. Mac-specific bugs squashed:
  321. -SmartMalloc somewhat faster, for a price (see above)
  322. -A few template bugs/aesthetics were fixed
  323. -Insert Template now deletes any existing selection before inserting the template.
  324.  
  325. Core bugs fixed: (See also "WHATSNEW.DOC")
  326. -some beziers crashing
  327. -speckles on some surfaces with normal textures
  328. -auto-bounding on Mac was read incorrectly and was always OFF
  329. -Some Height fields had holes or rips in them, partially fixed.
  330.  
  331.  
  332. Mac Notes
  333. This document describes the specific functions of the Macintosh version of POV-Ray.  It is  assumed that 
  334. you have read (or will read) the POVRAY.DOC file that describes the general operation of POV-Ray.
  335.  
  336. The POV-Ray Preferences dialog, up close
  337. This dialog sets up general preferences for the POV-Ray application that will be remembered between 
  338. renders, and between separate runs of POV-Ray itself.  Here is a description of what each item does:
  339.  
  340. 1.    Application Friendliness - The higher the number, the more time POV-Ray takes from other 
  341. applications, and the faster it runs (and the slower and more jumpy the other applications become.)
  342.  
  343. 2a.    Use Application's Default Rendering Options - To use the Application Default Rendering Options for 
  344. rendering files (ignoring each file's unique  Rendering Options), click here.  This is normally used 
  345. for multiple rendering sessions.
  346.  
  347. The Rendering Options dialog, up close
  348. This dialog sets up specific rendering options for the current scene file.  These options are stored with the 
  349. scene file itself (in the respurce fork) and are remembered on subsequent renders of the scene file.  Here is 
  350. a description of what each item does:
  351.  
  352. 1a.    Preset Image Sizes - Selecting an image size here will automatically fill in the width/height/from/to 
  353. fields below with a preset size.  Many screen sizes are listed here.
  354. 1b.    Width - Enter the total width of the image you want to render (in pixels.)  This number can be from 1 
  355. to 4096.
  356. (1c) Height - Enter the total height of the image you want to render (in pixels.)  This number can be from 1 
  357. to 4096.
  358. (1d) From row - Enter the top scanline, or starting row, of the image you want to render (in pixels.)  Only 
  359. enter a number here if you want to render a partial image.
  360. (1e) To row - Enter the bottom scanline, or ending row, of the image you want to render (in pixels.)  Only 
  361. enter a number here if you want to render a partial image.
  362.  
  363. (2) Progress - Sets how much information is displayed in the status window as the render progresses.  
  364. "No Info" is quiet, "Minimal Info" shows some memory usage information, "Progress Info" informs you 
  365. of each scanline, "Debug Info" shows internal debug information.  See POVRAY.DOC for more 
  366. information on the "+V" option.
  367.  
  368. (3) Image Quality - Enter a number (from zero to nine) to select the quality of the rendered image.  1 just 
  369. shows grey shapes, 5 shows colors, 9 shows full shadows lights and refraction.  The lower the number, 
  370. the lower the quality and the faster the render.See POVRAY.DOC for more information on the "+Q" 
  371. option.
  372.  
  373. (4) Auto-bounding - Turn this popup on to let POV-Ray optimize your scene by automatically "bounding" 
  374. the objects in your scene.  The number you set is the minimum number of main objects it finds before it 
  375. decides to kick in auto-bounding.  See POVRAY.DOC for more information on the "+MB" option.
  376.  
  377. (5a) Animate - Turn this on if you want to create a sequence of multiple images from this scene file.  See 
  378. POVRAY.DOC for more information on the "+K" option.
  379. (5b) Animate Settings - Click this to set up the number of frames, clock value range, etc. for animation.
  380.  
  381. (6) Language - Set this to which version of POV-Ray syntax this file is written in (version 1.0 or 2.0.)  
  382. See POVRAY.DOC for more information on the "+MV" option.
  383.  
  384. (7a) Compress Image - Turn this on to automatically use QuickTime image compression on the output 
  385. PICT file when it is saved.
  386. (7b) Compression Settings - Click this to set up what kind of image compression to use on the PICT file.
  387.  
  388. (8) Max Symbols - Set this to the largest number of #declared items in your scene file.  See 
  389. POVRAY.DOC for more information on the "+MS" option.
  390.  
  391. (9a) Do Anti-aliasing - Click here to toggle ╥anti-aliasing╙ of the image.  Although the rendering can take 
  392. much longer when this is on, the final image is much nicer looking, with fewer jagged edges.  See 
  393. POVRAY.DOC for more information on the "+A" option.
  394. (9b) Threshold - Enter a number here (from 0.0 to 1.0) that determines the threshold depth of anti-aliasing.  
  395. The closer to 0.0, the more anti-aliasing is done, the better the image looks, and the longer it takes to 
  396. render.
  397. (9c) Depth - Enter a number from 1 to 9 here to set the recursive depth of anti-aliasing.  The number of 
  398. rays is the square of this number, so a 3 would create 3*3 or 9 rays, etc.
  399. (9d) Jitter - Enter a number from 0.0 (no jitter) through 1.0 (lots of jitter.)  The higher this number, the 
  400. "wider" the anti-aliasing area, and the smoother it looks.
  401.  
  402. (10a) Create Targa Output File - To toggle the creation of a Targa-format output file during the render 
  403. process, click here.  This can allow you to stop POV-Ray partway through, and run it later to finish from 
  404. where it left off.
  405. (10b) Continue Rendering with Targa - To tell POV-Ray to load the Targa file from the previous run and 
  406. to continue where it left off last, click here.
  407.  
  408. (11) Save as defaults for new files - To save the current Rendering Option Settings as the Application's 
  409. Default Settings, click here.  All new documents will then acquire these default Rendering Options.
  410.  
  411.  
  412.  
  413. The Animation Settings dialog, up close
  414. This dialog sets up how many frames of animation to generate, and how the clock variable should change 
  415. across the frames.  Note the outer bounds (Initial and Final) are used for calculating the overall number of 
  416. frames and values for the scene.  The inner bounds (Start at and End at) are used to determine which 
  417. frames to actually generate for this session.  Here is a description of what each item does:
  418.  
  419. *** Frame Number.  This is just a reference number which counts the number of frames (or images) to 
  420. generate.  It starts at one, and increments for each frame.
  421.  
  422. (1a) Initial - This is a constant low bound for the frame counter.  It is always one.
  423.  
  424. (1b) Start At - This is the first frame number to start generating images for.  It can be any integer number 
  425. from "Initial" to "End at".
  426.  
  427. (1c) End At - This is the last frame number to generate images for.  It can be any integer number from 
  428. "End at" to "Final".
  429.  
  430. (1d) Final - This is the high bound for the frame counter.  It is the total number of frames that should be 
  431. generated for the scene.  This is used to calculate the span of clock values.
  432.  
  433. *** Clock Value.  This is a variable passed into POV-Ray, which can be used as a dynamically changing 
  434. animation variable (clock) in a scene file.
  435.  
  436. (1a) Initial - This is the clock value at frame #1.  It must be different than the "Final" clock value, but 
  437. otherwise may be any floating point value.
  438.  
  439. (1b) Start At - This is the displayed clock value at the "Start At" frame value.
  440.  
  441. (1c) End At - This is the displayed clock value at the "End At" frame value.
  442.  
  443. (1d) Final - This is the clock value at the "Final" frame #.  It must be different than the "Initial" clock 
  444. value, but otherwise may be any floating point value.
  445.  
  446. Advanced Tips
  447. To speed up rendering as much as possible on the Mac╔
  448. If you are in the beginning stages of scene creation, you often find yourself editing, rendering, editing, 
  449. rendering, etc.  To speed this up, try shrinking the image size to 32x32, and using the quick_color 
  450. statements and setting the Image Quality down to about 3.  Also hiding the image window during 
  451. rendering speeds up POV-Ray a bit.  If you are generating a final scene, try temporarily booting your Mac 
  452. with no (or few) extensions on.  Some of these, especially screen savers and network connections, can 
  453. really slow things down.  POV-Ray grabs more time if it is in the foreground, so don't switch it out 
  454. behind others.  Also, choose the POV-Ray Preferences item from the Edit menu, and set the Application 
  455. Friendliness throttle way up, towards 11.  Doing all of this can dramatically speed up the scene generation.  
  456.  
  457. To edit large scene files╔
  458. Because of the current file size limitation in the POV-Ray built-in editor, you must make sure that the main 
  459. ╥.POV╙ file is no larger than 32K bytes.  To edit and  render larger files, you must use another text editor 
  460. to break the file into a small .POV file, which uses the #include statement to use the larger file(s).  You can 
  461. then edit and render the .POV file with POV-Ray.  The larger include files must still be edited with another 
  462. text editor.  Note that if you use a word processor to do this (e.g. MacWrite, Word, WriteNow, etc.), you 
  463. must save the file in ╥Text-Only╙ format.
  464.  
  465. To batch-render a series of individual scene files╔
  466. If you are rendering a few files of different output sizes/parameters, open each file in POV-Ray and set up 
  467. its ╥Rendering Options╙ the way you want, and close each file when done.  There should be no POV-Ray 
  468. Source file window open now.  Don't quit POV-Ray, but instead just switch to the System 7 Finder.  
  469. Select all the files which you just opened and set options for.  Now drag them over onto the POV-Ray 
  470. application icon (or convenient application alias) and drop them on it.  POV-Ray will (by default) render 
  471. each file with its own option settings, and save each image before starting the next.
  472.  
  473. If during this batch rendering process, you want to add more files to the list, just drag the new files onto 
  474. POV-Ray just like before.  These new files will be added to the end of the list of files to batch-render.
  475.  
  476. To stop the batch rendering in progress, just choose "Stop Rendering" from the Render menu, or press 
  477. command-period.  The current scene will be interrupted, and all remaining scenes will not render.  To 
  478. resume, you will have to drop the remaining scene files onto POV-Ray again.
  479.  
  480. If you want a series of images to all be rendered, but with identical settings, then do this:  Open any one of 
  481. the files to be rendered, and set up its Rendering Options the way you want all the files to be done.  Now 
  482. choose ╥Application Preferences╙ from the File menu.  Turn on the ╥Use Application Default Options╙ 
  483. radio button, and turn on the ╥Save current file's rendering options as the default╙ checkbox, and click the 
  484. Save button.  Close the source window, but DON'T QUIT POV-RAY YET!  Now switch back to the 
  485. Finder, select all the files, and drag them onto the POV-Ray application icon, just like before.  This time, 
  486. all the files will ignore their individual settings, and use the default application setting.
  487. NOTE: In the interest of safety and user sanity, POV-Ray doesn't remember this override state, but always 
  488. returns to ╥╔each file's settings╔╙ when it is first run.
  489.  
  490. To generate a QuickTime movie from POV-Ray╔
  491. Use the ╥clock╙ variable in expressions in your scene, to scale, translate, or rotate objects.  Then use the 
  492. ╥Rendering Options╙ menu item, turn on the ╥Animate╙ checkbox, and click the ╥Settings╙ button to set the 
  493. number of frames and the range of the clock variable.  When you render the file, it will render multiple 
  494. times and generate a series of PICT files.  You can then use MacroMind Director, Apple's Convert-to-
  495. Movie, my FreeWare "MooVer" utility, or some other application to ╥import╙ the series of PICT files, and 
  496. save the result as a QuickTime movie.  
  497.  
  498. To stop the animation rendering in progress, just choose "Stop Rendering" from the Render menu, or 
  499. press command-period.  The current scene frame will be interrupted, and all upcoming frames will not 
  500. render.
  501.  
  502. To resume from some frame, you can choose "Animation Settings" from the Rendering Options dialog, 
  503. and set the "Start At:" to start where you left off.  POV-Ray will then begin rendering from that frame to 
  504. the "End At:" frame.
  505.  
  506. An example of a spinning box and a moving sphere is shown below:
  507.     box { <-1,-1,-1> <1,1,1> rotate clock*y }
  508.     sphere { <0,0,0> 2 translate clock*z/36-5 }
  509. If you set up the frames to go from 1 to 20, and the clock value to go from 0 to 360, then the above box 
  510. will make one complete revolution, and the sphere would move from -5 z to +5 z.  The math is left as an 
  511. exercise to the reader :-)
  512.  
  513. Animation tip:  If you are creating an animation that you want to smoothly loop, there is a subtle problem 
  514. you might run into.  If you set up the animation to go from 0.0 to 360.0 degrees, you will notice that the 
  515. first and last frames are the same, since in the 
  516. "polar regions", zero is the same as 360.  This means that at the loop point of the movie, there will be a 
  517. slight stall because the same frame is displayed twice.  To get around this problem, you must do the 
  518. following:
  519. Set the Final frame to be one more than you actually want (e.g., 101), and set the "End At:" frame at one 
  520. less than this (e.g., 100).  Now set the "Start At:" frame number to 1, and set the Initial and Final clock 
  521. values to the full range (e.g., 0.0 to 360.0)... whew, now you are ready to make a movie!  Of course, you 
  522. could just delete one of the frames and have a 99 frame movie, but that would be too easy.
  523.  
  524. How do I edit the Template file and add my own Templates?
  525. The POV-Ray template importer reads a specially formatted text file, and builds a multi-level 
  526. (hierarchichal) menu structure, that connects specific menu items to blocks of text that can be automatically 
  527. inserted into the user's text file at the current cursor insertion point, simply by choosing that menu item.  
  528. The user imports the text once (or has it automatically imported every time they start POV-Ray).  This 
  529. process builds the menu structure.  Then whenever the user wants a particular item, he chooses it off the 
  530. TEMPLATES menu, and it is inserted into the current text file.  Although the syntax and code of the 
  531. template reader can handle at least 4 menus deep, it is suggested to keep it down to 2 levels and group 
  532. things in a fairly flat and logical manner.
  533.  
  534. When the Import Template reader sees a command string in the form @xxx, starting in the first character 
  535. of the line, it reads the line as a command and processes it accordingly.  The 4-character command is not 
  536. case sensitive, so "@mt1" and "@Mt1" are legal, though I would prefer to have them remain all lower 
  537. case.  Note that empty lines are not skipped, they are added to the current menu item text.  If this weren't 
  538. done, you couldn't add any blank lines as part of a template into your file.  The side effect of this is that if 
  539. you want to separate items in the template file for legibility, you MUST use the @com comment 
  540. command.
  541.  
  542. COMMANDS
  543. @com.Any text here...
  544. This is a comment line, ignored by the parser.
  545.  
  546. @mt1.Title
  547. This means define a new level-1 menu, and give it the name "Title".  All level 2 menus will go under this 
  548. level 1 menu, until another level 1 menu is defined.  There must not be anything else on these special lines.
  549.  
  550. @mt2.Title2
  551. This means define a new level-2 menu (under a previously defined level 1 menu) and give it the name 
  552. "Title2".  Any lines immediately following this line will be used as the text to be inserted.  Blank lines are 
  553. valid and counted, so that the user can insert blank lines.  The end of the text block is determined when the 
  554. next @xxx command is reached.  Yes, I know you're thinking, "Oh good!  I can define @mt3 & @mt4!"  
  555. Let's not do this, I don't think it is a good U.I. idea :-)
  556.  
  557. @@@@
  558. This is an end-of-file mark, ignore anything after this in the file.
  559.  
  560. EXAMPLE
  561. @mt1.Statements
  562. @mt2.File Boilerplate
  563. // Persistence of Vision Ray Tracer Scene description file
  564. // File: ??.pov
  565. // Version: 3
  566. // Description: ??
  567. // Date: mm/dd/yy
  568. // Author: ??
  569. //
  570.  
  571. @mt2.Background
  572. // Set the color of the background (sky)
  573. background { color red 0.1 green 0.3 blue 0.8 }
  574. @mt2.Camera
  575. // set viewer's position in the scene
  576. camera
  577. {
  578.   location  <0,  1, -6>   // <X Y Z>
  579.   direction 2.0*z         // which way are we looking <X Y Z>
  580.   up        y             // which way is +up <X Y Z>
  581.   right     4/3*x         // which way is +right <X Y Z> and aspect ratio
  582.   look_at   <0,  0,  0>   // point center of view at this point <X Y Z>
  583. }
  584. @mt1.Textures
  585. @mt2.Pigment-rgb
  586.   pigment { color rgb <1,2,3> }
  587. @mt2.Pigment-agate
  588.   pigment { agate agate_turb 1 }
  589. @@@@
  590. That was an eof token, so all this after it is ignored.
  591.  
  592. Bugs, Quirks, and Future Directions
  593.  
  594. The Bad News...
  595. There is a maximum limit of 32,000 characters (approx. 32K bytes) in source files in the built-in text 
  596. editor window.  The text editor will not allow you to open or create files bigger than this.  This is due to a 
  597. limitation of the Macintosh TextEdit package (i.e., Programmer Laziness.)  Although the main file to be 
  598. rendered must be less than 32K in size, any #included (.INC) files may be of any size.  You will just need 
  599. to use some other editor or word processor to edit those.  If you do use a word processor to edit them, 
  600. remember to save your files in TEXT-only format.
  601.  
  602. There is this same 32K limit in the Status window text.  When the Status Window gets close to this limit, 
  603. it just drops things off the top as it adds to the bottom.  So you always have the last 32K of text in the 
  604. window.
  605.  
  606. If you create and render a scene file with nothing in it, it will display an error "no objects found in scene."  
  607. If you try to run the same scene again, you will get some odd error messages.
  608.  
  609. After each rendering job, POV-Ray "loses" about 1 KByte of RAM memory.  This sloppy phenomenon, 
  610. sometimes known in programming circles as a "memory leak", is not harmful.  However, after you've 
  611. done a large number of renders without quitting the application, you may eventually get an "out of 
  612. memory" error.  Just quit and restart POV-Ray, and it will be fine for awhile again.  This will be more of a 
  613. problem if you are doing animation renders with lots of frames.  You may have to break it into multiple 
  614. runs, or increase POV-Ray's application heap size.  This was addressed prior to release, but not all leaks 
  615. were found... it will be completely fixed in a future release.  All "direct" memory leaks are fixed, what's 
  616. left seems to be caused by calling runtime routines that themselves leak.
  617.  
  618. POV-Ray should be creating the POV-Ray Virtual Image Buffer file in the Temporary Items folder if it is 
  619. running under System 7, it currently does not.
  620.  
  621. There is still an occasional quirk in the vertical scrollbar of the Status window, where it will get out of 
  622. sync if you scroll it while the window is being filled.  Nothing is lost, and if you scroll to the top and back 
  623. to the bottom, all returns to normal.
  624.  
  625. There are reports that the "Finder Balloon Help" of the POV-Ray Application (turn on Balloon Help and 
  626. point at app in the Finder) does not work on some Macs.  It will report a Finder "Type -192" error.  It 
  627. seems to work properly on other machines.  This may be due to a corrupt desktop database, although 
  628. rebuilding the desktop was reported not to help.
  629.  
  630. Under System 6.x, POV-Ray will not automatically open a document that is double clicked from the 
  631. Finder.  You must run POV-Ray, then open the file from the File menu.  Double-clicking documents 
  632. DOES work properly in System 7, and in fact, multiple file drag-n-drop is supported.  This missing 
  633. System 6 feature was an intentional omission due to time constraints and the low priority of the feature.
  634.  
  635. If you are using a virtual image buffer for a large image, it is not advisable to use the "Size Image to 
  636. Window" mode, because the image won't display properly.  This is only a display problem, It will save 
  637. properly when finished.
  638.  
  639. Adobe Photoshop prior to version 2.5 ignores the vertical-flipped bit of the TARGA files created by POV-
  640. Ray, and displays them upside down.  Version 2.5 fixes this problem.
  641.  
  642. With System 7 Virtual Memory (VM) on, and anti-alias setting on, and an anti-alias on, the VM file will do 
  643. some thrashing occasionally if your rendering requires a virtual image buffer.  This will just slow things 
  644. way down; it doesn't cause any crashes.
  645.  
  646. The Good News
  647. Coming sometime after version 3.0...
  648. *  Allow selecting an arbitrary area in Image window, and then re-rendering just that area (x1,y1 to 
  649. x2,y2).. more flexible than the current start/end scanline method
  650. *  Allow user to scroll the Image window
  651. *  Let user pick file signature for PICT and Targa file formats.  Currently, PICT files are saved with 
  652. TeachText's signature and Targa files are saved with PhotoShop's (PICT creator type is currently saved in 
  653. scene file's fPrf resource, & could be edited with ResEdit.)
  654. *  Built-in QuickTime movie support
  655. *  TIFF and PICT image (image-map) support for POV-Ray
  656. *  TrueType font support (extruded characters.. need generic POV-Ray syntax additions for typeface 
  657. import?)
  658. *  Allow saving image directly to GIF or 8 bit Mac PICT format (currently just 24 bit PICT now.)
  659. *  Mac Network (distributed) rendering
  660.  
  661. The Mac Source Editor needs a _major_ facelift, to include:
  662. *  Abandon stock TextEdit, support source files larger than 32K chars
  663. *  Support tabs
  664. *  Search and replace features should be added
  665. *  Shape prototype generation, esp. torus and other tough ones
  666. *  Add balanced curly brace checking
  667. *  Simultaneously edit multiple source files, useful for Includes
  668.  
  669. One possible way to enhance the editor is to give up on the built-in text editor altogether, and tell the user 
  670. to use BBEdit or some other text editor, and we could break POV-Ray into a faceless rendering engine that 
  671. accepts AppleEvents.  The options dialogs could be supported by a stand-alone application that could alter 
  672. the file's settings prior to rendering.  This makes POV-Ray more loosely coupled, but paves the way for 
  673. drop-in editors and network rendering.  Besides the time it would take to do this, an interesting obstacle to 
  674. overcome is how the rendering engine would display its image.  If it was not so tightly integrated, quick 
  675. changes and re-rendering sessions may be more awkward.  These are some interesting ideas... we are 
  676. interested in hearing from users as to which way future versions of POV-Ray should head, let us know!
  677.  
  678. The Source Code
  679. POV-Ray is a team effort, and the team members use Compuserve's Graphics Developers forum 
  680. (GRAPHDEV) to keep abreast of changes and suggestions.  Before you jump in and write massive 
  681. enhancements, we suggest that you contact any of the team members and get to know the guidelines.  We 
  682. are an easy going bunch, and very friendly and interested in helping newcomers.  And who knows, we 
  683. may be working on the very same features you want to add, or your enhancement may be one we're 
  684. hoping to see done.
  685.  
  686. Before you publically post altered source or executables, please review the POV-Ray legal documentation 
  687. for copyright restrictions and rules of distribution.  POVLEGAL.DOC can be found in any of the archives.  
  688. To restate our position: please contact us directly with any bug fixes or enhancements.  We can then 
  689. incorporate them into the next general release.
  690.  
  691. The executables released by the POV Team for the Macintosh are built using Think C 6.0.  It is possible to 
  692. create even faster POV-Ray executables using a mix of Gnu C and MPW, but for a straight compilation, 
  693. Think C 6.0 is a little smaller and faster than MPW 3.2 or MPW 3.3.
  694.  
  695. You will find the source code in two sections in the POVSRC archive.  The main portion of POV-Ray is in 
  696. POVSRC:SOURCE:.  The additional Macintosh-specific source code is in POVSRC:MACHINE:MAC-
  697. Source:.  These two sets of source should then be put together into a single POV-Ray Source folder before 
  698. building (any name is fine.)
  699.  
  700. Think C Compiler Notes
  701. When compiling, you must use Think C 7.0 or later.
  702.  
  703. You should first make a COPY of your "Standard Libraries:ANSI" library's Project file, and rename your 
  704. copy to ╥ANSI.020.FPU╙.  This will be the ANSI library you'll be using for POV-Ray.  Choose the 
  705. Edit:Options menu, and change the following:  Think C:Compiler settings, turn on all checkboxes except 
  706. "4 byte ints" and "8 byte Doubles".  In Code Optimizations:turn on all, but not the Global Optimizations.  
  707. Debugging:turn off all.  Prefix:add a #define _NOCONSOLE_.  Choose the menu Project:Set Project 
  708. Type, and turn on "Separate Strs".  Now "update" to compile all the modules.
  709.  
  710. Here are the additional steps to create the POV.╣ project file from scratch.  Start up Think C, create a new 
  711. project called POV.╣, and add all the .c source files to the project.  Here's the current segmenting strategy:
  712. === Segment (povNEditor) ===
  713. FileQueue.c
  714. POV.c
  715. POVMalloc.c
  716. ScreenUtils.c
  717. TextEditor.c
  718. === Segment (textures) ===
  719. pigment.c
  720. texture.c
  721. txttest.c
  722. === Segment (tokenize) ===
  723. express.c
  724. matrices.c
  725. tokenize.c
  726. === Segment (macwindows) ===
  727. animate.c
  728. imagewindow.c
  729. popupmenu.c
  730. printf2window.c
  731. progressdialog.c
  732. savecmppict.c
  733. stdcompressionglue.o
  734. templatemenu.c
  735. === Segment (files) ===
  736. dump.c
  737. gif.c
  738. gifdecod.c
  739. iff.c
  740. raw.c
  741. targa.c
  742. === Segment (parse) ===
  743. parse.c
  744. === Segment (render) ===
  745. normal.c
  746. povray.c
  747. ray.c
  748. render.c
  749. vect.c
  750. === Segment (polyquad) ===
  751. poly.c
  752. quadrics.c
  753. === Segment (heightfields) ===
  754. hfield.c
  755. === Segment (cameraNlights) ===
  756. camera.c
  757. lighting.c
  758. === Segment (primparse) ===
  759. boxes.c
  760. colour.c
  761. csg.c
  762. image.c
  763. objects.c
  764. planes.c
  765. point.c
  766. === Segment (primparse2) ===
  767. blob.c
  768. bound.c
  769. cones.c
  770. discs.c
  771. === Segment (primparse3) ===
  772. spheres.c
  773. triangle.c
  774. === Segment (bezier) ===
  775. bezier.c
  776. === Segment (ansi) ===
  777. ANSI-020.FPU.NoConsole
  778. MacTraps
  779. MacTraps2
  780.  
  781. Choose the Edit:Options:Think C: menu, and change the following:  Language:turn on Check Pointer 
  782. Types and Think C Language Extensions.  Compiler settings, turn on all checkboxes except "4 byte ints" 
  783. and "8 byte Doubles".  Code Optimizations:turn on all.  Debugging:turn off all.  Prefix:add a #define 
  784. _NOCONSOLE_.  Choose the menu Project:Set Project Type, and turn on "Separate Strs", set the Creator 
  785. to "PvRy", set the Size Flags to 58E0, set the type to Application, and set the Partition to 1000.  Insert the 
  786. following into the Prefix options from the Edit menu:
  787. #define SystemSixOrLater    true
  788. #define _NOCONSOLE_   // turn off Think C console I/O
  789. #include <MacHeaders>
  790. #define NEEDS_68020 1   // turn on to force 68020 or better CPU code
  791. #define NEEDS_COLORQD 1 // turn on to force Color Quickdraw ROM Support
  792. #define NEEDS_32BITQD 1 // turn on to force 32Bit Quickdraw ROM Support
  793. #define NEEDS_FPU 1     // turn on to force 68881 FPU calls
  794. #define USE_NATIVE_MALLOC 1 // turn off to use C's malloc(), on for Mac's NewPtr()
  795.  
  796. After you build the application, you must set the application's (preferred) memory size to 2500, using the 
  797. Finder's "Get Info" menu item.  This is currently the only way to set the minimum and preferred memory 
  798. sizes differently.
  799.  
  800. MPW C Compiler Notes
  801. The non-FPU version of POV-Ray was compiled under MPW, because the code generated was too big for 
  802. Think C (specifically, hfield.c.)  An MPW compile of the FPU version of POV-Ray is possible, but 
  803. generates a noticeably larger and slower application.
  804.  
  805. POV-Ray has been compiled and tested using Apple's MPW C compiler, 3.3.1  The make file supposedly 
  806. supports MPW 3.2 as well, but has not been tested.
  807.  
  808. In order to compile POV-Ray with the included make file, you will first need to manually create an empty 
  809. folder inside the POV-Ray Source folder called ╥obj╙.  The object files will be stored in there, instead of 
  810. being sprinkled through the source code folder.
  811.  
  812. There are quite a few flags used to turn on and off options (FPU, native-malloc, etc.), these are in the 
  813. Make file itself.
  814.  
  815. There are some warnings that show up in the POV-Ray core code, all of them are due to unused function 
  816. parameters.  These are, in the immortal words of Douglas Adams, ╥Mostly Harmless.╙
  817.  
  818. Metrowerks Compiler Notes
  819.  
  820.